home *** CD-ROM | disk | FTP | other *** search
/ Aminet 37 / Aminet 37 (2000)(Schatztruhe)[!][Jun 2000].iso / Aminet / text / edit / BareED.lha / BareED / tool / BitMapSaver.doc < prev    next >
Encoding:
Text File  |  1999-12-27  |  14.3 KB  |  446 lines
  1. BitMapSaver's doc            $VER: Bitmapsaver 1.3 (06/15/96)
  2.  
  3. Author of documention and object file: Jörg van de Loo.
  4.  
  5. Date: 06/19/93 (updated 06/15/1996)
  6.  
  7. FORMAT: BITMAPSAVER {<NAME>}TO{<NAME>}[OPT CMAP|SPRITE|C|QUICK|RAW|PEN|RAWHDR|SEPRIT|RGB32]
  8.  
  9.  
  10. FROM/A,TO/K,OPT/K/M,CMAP/S,SPRITE/S,C/S,QUICK/S,RAW/S,PEN/S,RAWHDR/S,SEPRIT/S,RGB32/S
  11.  
  12. Description:
  13.  
  14. Within  this  little program it's possible to translate any IFF-ILBM file with
  15. less  or  equal  8 bitplanes to an assembler or C source which can be directly
  16. included.
  17.  
  18. It's  a  quite  old  tool  but one that can be used today from within a Shell-
  19. script.
  20.  
  21. ---------------------------------
  22.  
  23. C           Make code for the C-language, default assembler.
  24. SPRITE        Store datas in the format needed by a SPRITE-object,
  25.         default BitMaps.
  26. PEN        Store datas as 8-bit pen-array instead of BitPlanes
  27.         or sprite-object.
  28. RAW        Generate binary datas only.
  29. CMAP        Store 4-bit RGB colourtable, default none.
  30. RGB32        Store colour-values as V39 and up RGB32 colour format
  31.         when option CMAP was chosen, default 4-bit.
  32. SEPRIT        Split RAW-file, when option CMAP was chosen,
  33.         into image and cmap-file.
  34. RAWHDR        Write binary raw-file header instead of none if option
  35.         RAW was chosen.
  36. QUICK        Do it faster.
  37.  
  38. Example:
  39.  
  40. 4> bitmapsaver "work:dtp/pictures/gsx-r 750.iff" RAM:bike.c opt c cmap
  41.  
  42. Will  generate  a file which can be used for the C-language, the datas will be
  43. stored  as  bitplanes  (each  plane  after  another),  the BitMap-structure is
  44. initialized but without pointed planes to it, the colourmap is stored, too.
  45.  
  46.  
  47. ---- Generated code... ----
  48.  
  49. C-language code ...
  50.  
  51. #ifndef    GRAPHICS_GFX_H
  52. #include    "graphics/gfx.h"
  53. #endif
  54.  
  55. #ifndef    EXEC_TYPES_H
  56. #include    "exec/types.h"
  57. #endif
  58.  
  59. struct BitMap NewBitMap =
  60. {
  61.     76,        /* Bytes per row */
  62.     60,        /* Height */
  63.     0,        /* Flags */
  64.     4,        /* Depth */
  65.     0,        /* Strictly for longword adjustment */
  66.     0,        /* Pointer to plane 1 */
  67.     0,        /* Pointer to plane 2 */
  68.     0,        /* Pointer to plane 3 */
  69.     0,        /* Pointer to plane 4 */
  70.     0,        /* Pointer to plane 5 */
  71.     0,        /* Pointer to plane 6 */
  72.     0,        /* Pointer to plane 7 */
  73.     0        /* Pointer to plane 8 */
  74. };
  75.  
  76.  
  77. UWORD BitMap_Data[] =  /* Important Note: You have to force the
  78.             datas on your own to chip-memory!
  79.             Also you have to set the address of
  80.             each plane to the Bitmap structure! */
  81. {
  82. /* Plane1 */
  83.  ....,
  84. /* Plane2 */
  85.  ....,
  86. /* Plane3 */
  87.  ....,
  88. /* Plane4 */
  89.  ....
  90. };
  91.  
  92. UWORD Colors[16] =
  93. {
  94. 0x0AAA,0x0000,0x0EEE,0x068B,0x0E44,0x05D5,0x004D,0x0E90,0x0F60,0x0555,
  95. 0x0FE0,0x0080,0x00D0,0x00CC,0x006F,0x000A
  96. };
  97.  
  98.  
  99. Asm-language code ...
  100.  
  101. _Bitmap
  102.     dc.w    76            ; Bytes per row
  103.     dc.w    60            ; Number of lines
  104.     ds.b    1            ; Flags
  105.     dc.b    4            ; Depth
  106.     ds.w    1            ; Strictly for longword alignment
  107.     dc.l    _Plane1            ; Pointer to plane 1
  108.     dc.l    _Plane2            ; Pointer to plane 2
  109.     dc.l    _Plane3            ; Pointer to plane 3
  110.     dc.l    _Plane4            ; Pointer to plane 4
  111.     dc.l    0            ; Pointer to plane 5
  112.     dc.l    0            ; Pointer to plane 6
  113.     dc.l    0            ; Pointer to plane 7
  114.     dc.l    0            ; Pointer to plane 8
  115.  
  116.     SECTION    "BITMAP",DATA_C        ; Forced to chip memory
  117. _Plane1
  118.     dc.w ....
  119. _Plane2
  120.     dc.w ....
  121. _Plane3
  122.     dc.w ....
  123. _Plane4
  124.     dc.w ....
  125.  
  126.     SECTION    "RGBColorTable",DATA
  127. _ColorTable
  128.     dc.w    $0AAA,$0000,$0EEE,$068B,$0E44,$05D5,$004D,$0E90,$0F60,$0555
  129.     dc.w    $0FE0,$0080,$00D0,$00CC,$006F,$000A
  130.  
  131. _CMAPNumEntries
  132.     dc.w    16            ; Number of words
  133.  
  134.  
  135. The  reason why the BitPlane-pointers aren't initialized for the C-language is
  136. because  not  all  C-compilers/linkers support direct hunk-chip sections. Look
  137. into the file Box.c how to initialize them on your own.
  138.  
  139. ---------------------------------
  140.  
  141. Sprites:
  142. Until  Kickstart  3.0  a  sprite had a maximum of 16 pixel width, up from this
  143. Kickstart  the  maximum-width  for  a  sprite  has grown to 64 pixels. Because
  144. sprites  have  a  maximum of 4 colours (depth=2 - without tricks!) BitMapSaver
  145. ever  and  only takes the first 2 bitplanes for the spriteimage, the other are
  146. ignored.
  147.  
  148. ---------------------------------
  149.  
  150. Images:
  151. Images   have  almost  the  same  binary  format  like  bitplanes,  only  that
  152. image-bitplane-datas  are  combined  within  one memory block, i.e. the normal
  153. and the select image can only lie after each other in memory:
  154.  
  155. Image: 48 * 32 pixel, 3 bitplanes (8 colours)
  156.  
  157.        Thus the normal image is stored first into memory:
  158.        48 / 8 * 32 * 3 = 576 bytes and right after this
  159.                              the select image is stored:
  160.        48 / 8 * 32 * 3 = 576 bytes
  161.        makes a total of 1152 for both images.
  162.  
  163. If  you use a brush with more than one image, you have to reorder the bitplane
  164. format  to  the  image  format  on  your  own,  perhaps  a  future  version of
  165. BitMapSaver should do the work?
  166.  
  167. Taken out of "intuition/intuition.h|i"
  168.  
  169.  STRUCT(URE) Image(,0)
  170.  WORD    ig_LeftEdge    ; starting offset relative to rastport's X offset (normally zero)
  171.  WORD    ig_TopEdge    ; starting offset relative to rastport's Y offset (normally zero)
  172.  WORD    ig_Width    ; width in pixels (must! be word-aligned)
  173.  WORD    ig_Height    ; number of lines (rows)
  174.  WORD    ig_Depth    ; depth (number of planes)
  175.  APTR    ig_ImageData    ; pointer to the actual image datas (Chip-RAM)
  176.  BYTE    ig_PlanePick    ; bitmask for "plane(x) has to blit to display"
  177.  BYTE    ig_PlaneOnOff    ; bitmask for plane datas all one (1) or all zero (0)
  178.  APTR    ig_NextImage    ; pointer to the next image or nil
  179.  (LABEL    ig_SIZEOF)
  180.  
  181.  
  182. To make pixel-width word-aligned (boundray 16) :
  183. C:     width = ((width + 7) & -8);
  184.  
  185. ASM:   move.w   width,d0
  186.        addq.w   #7,d0
  187.        andi.w   #-8,d0
  188.        move.w   d0,width
  189.  
  190.  
  191.  PlanePick = 13 = % 00001101 - means: blit datas as plane 0, 2, 3 but not plane 1!
  192.  PlaneOnOff = 0 = % 00000000 - means: clear all datas of plane 1
  193. or
  194.  PlaneOnOff = 2 = % 00000010 - means: set all datas of plane 1 to one
  195.  
  196. In  this example the image has only 3 bitplanes where the image structure says
  197. there  are  four.  This  means  that the image itself ( ImageData ) has only 3
  198. planes.  So  in  our  example  plane  0,  2  and  3  will  be  blitted  to the
  199. corresponding bitplanes of the RastPort.
  200. If  PlaneOnOff  is  set  to zero, the concerned RastPort area of bitplane 1 is
  201. cleared, or if PlaneOnOff is set to 2, this area datas will be set to one.
  202.  
  203. For plain images use:
  204. PlanePick  %00001111 = 15
  205. PlaneOnOff %00000000 =  0
  206.  - means blit plane 0,1,2 and 3 - PlaneOnOff unused.
  207.  
  208. Resume:
  209.  Only  where  PlanePick's  bitplanes  are  set to zero, PlaneOnOff is taken to
  210.  check for set or unset bits.
  211.  
  212.  In  our  example  this  means  in a 16 colour display all 4 bitplanes will be
  213.  blitted  to  the  display, if the display has less colours, only the affected
  214.  bitplanes will be blitted.
  215.  
  216.  But,  if  the display has more colours (e.g. 256) the upper 4 bitplanes which
  217.  are set to zero (%0000 0000 - PlaneOnOff) are cleared in the display.
  218.                    ¯¯¯¯
  219. Example for a 16 colour image:
  220.  
  221.    PlanePick  %00001111 = 15
  222. OR PlaneOnOff %00000000 =  0
  223.                           --
  224.                           15   - OK.
  225.  
  226.    PlanePick  %00001111 = 15
  227. OR PlaneOnOff %00001111 = 15
  228.                           --
  229.                           15   - Also OK.
  230.  
  231.    PlanePick  %00001111 = 15
  232. OR PlaneOnOff %11111111 = 255
  233.                           ---
  234.                           255  - Wrong !!!! - means 256 colours.
  235.  
  236.    PlanePick  %00001111 = 15
  237. OR PlaneOnOff %00010000 = 16
  238.                           --
  239.                           31   - Also wrong !!!! 32 colours.
  240.  
  241. ---------------------------------
  242.  
  243. QUICK:
  244. This  option  is  only  suitable when writing C- or assembler source codes. It
  245. will  allocate  a buffer (20 KB) where the datas are written to. When now this
  246. buffer  is  full,  the  contents  of it are saved to disk. This gains a lot of
  247. time even if you are writing your datas to a fast medium (e.g. RAM DISK).
  248.  
  249. ---------------------------------
  250.  
  251. RAW:
  252. Sometimes  it  is not suitable to generate a source-code for images, e.g. when
  253. the  images are so tall that MBs are needed to include them, e.g. a picture of
  254. 960*724  width and 8 planes will need 2,296,046 bytes of memory in ASCII form.
  255. Instead  of  it you may include directly the binary image datas - here 695,552
  256. bytes.
  257. You  have  to  force  those  converted  datas  on  your own to Chip-memory (if
  258. required);  also you have to create on your own a bitmap-structure (if needed)
  259. and compute each address for the bitplanes.
  260.  
  261. ---------------------------------
  262.  
  263. PEN:
  264. This  option  is  available  when generating source codes ( C or asm) and when
  265. writing  raw-datas.  Instead  of  the  output-data  format "Bitplanes" it will
  266. force  the  datas  to  an  8-bit  pen array which can "blitted" to the display
  267. (virtual screen) via:
  268.  
  269.     OS 1.x  and up    SetAPen()/WritePixel()
  270.     OS 2.x  and up    WritePixelArray8()
  271.             WritePixelLine8()
  272.     OS 3.1    and up    WriteChunkyPixels()
  273.  
  274. This  option  is indeed useful if you have installed a 3rd party graphic board
  275. or  -  if  you  are  in  a surround of OS 3 and you want to adjust the pens to
  276. those  of  that  screen.  Even  when  you write games it is easier to use this
  277. format  instead  of  bitplanes to let the background shine through a specified
  278. colour.
  279.  
  280.  
  281. Altough  I know how to decode bitplane colour index' to the true-colour format
  282. I  don't know if I should implement it into BitMapSaver, i.e. I have a written
  283. a  utility  (labelled  Viewer)  that already de- and encodes picture of 24 bit
  284. depth  (including  HAM6  and  HAM8 images) to the true-colour format (RGB). If
  285. you are interested in such a conversion tell me.
  286.  
  287. ---------------------------------
  288.  
  289. CMAP:
  290. Using  this  option  enables  the storing of the 4-bit colour values either in
  291. the ASCII- or binary file.
  292.  
  293. ---------------------------------
  294.  
  295. RGB32:
  296. If  the option "CMAP" was not chosen, this statement (RGB32) has no effect. It
  297. does  only  work  in conjunction with the option "CMAP". If both are set (CMAP
  298. and!  RGB32)  the  colourtable  is  stored  as 8-bit colour index which can be
  299. directly used by OS 3.x and up function LoadRGB32() or tag-item SA_Colors32.
  300.  
  301. ---------------------------------
  302.  
  303. SEPRIT:
  304. When  you  have chosen the options "RAW" and "CMAP" for one image, the colour-
  305. table  for this file is stored right behind the image data area. When now this
  306. connected  file  is  loded  into  Chip-memory,  the  RGB-colourtable  lies  in
  307. Chip-memory,  too.  To  avoid this, you may split this file into two; one will
  308. contain  the  image  datas, the other the colour-datas. The keyword to do this
  309. is  "SEPRIT". A file with the suffix ".cmap" is saved in the same directory as
  310. the  file  containing  the image datas, - when your image-file is named with a
  311. suffix, right in front of your suffix a second is stored, e.g.
  312.  
  313. 4> bitmapsaver box.bsh to ram:Box.bin opt cmap raw seprit
  314.  
  315. Result:
  316.  
  317. RAM Disk:Box.bin
  318. RAM Disk:Box-cmap.bin
  319.  
  320. or:
  321.  
  322. 4> bitmapsaver box.bsh to ram:box opt cmap raw seprit
  323.  
  324. Result:
  325.  
  326. RAM Disk:box
  327. RAM Disk:box.cmap
  328.  
  329. ---------------------------------
  330.  
  331. RAWHDR:
  332. RAWHDR  means RAW-HEADER and will allow you to save the important informations
  333. of the image along with the raw-file when option RAW was chosen.
  334.  
  335. The basic structure (header) is 16 bytes in size:
  336.  
  337.  struct RAWHEADER        STRUCTURE RAWHEADER,0
  338. {
  339.     ULONG    ID;            ULONG    rwh_ID
  340.     UWORD    ImageWidth;        UWORD    rwh_ImageWidth
  341.     UWORD    ImageHeight;        UWORD    rwh_ImageHeight
  342.     UBYTE    Depth;            UBYTE    rwh_Depth
  343.     UBYTE    kludgefill_0;        UBYTE    rwh_kludgefill_0
  344.     UWORD    Flags;            UWORD    rwh_Flags
  345.     UWORD    BMWidth;        UWORD    rwh_BMWidth
  346.     UWORD    Colors;            UWORD    rwh_Colors
  347. };                    LABEL    rwh_SIZEOF
  348.  
  349.  
  350. ID    = BMAP for non-interleaved bitmap datas
  351. ID    = PARY for pen array datas
  352.     ImageWidth    = real image's width, e.g. 17    (0x11)
  353.     ImageHeight    = number of rows, e.g. 15    (0xF)
  354.     Depth        = number of bitplanes, e.g. 3    (0x3)
  355.     kludgefill_0    = (ever) zero
  356.     Flags        = bit 0 set when this raw-data file
  357.               contains a colourmap at its end
  358.             = bit 7 set when the colourmap is
  359.               stored in the RGB32 format
  360.     BMWidth        = boundary 16 of ImageWidth, 0x11 to 0x20
  361.     Colors        = Number of used colours
  362.  
  363. In  our  example  an  image of 17 * 15 pixel and 3 bitplanes
  364. without a colormap would look like this:
  365.     BMAP 0011 000F 03 00 0000 0020 0008    or
  366.     PARY 0011 000F 03 00 0000 0020 0008
  367.  
  368. When saved along with a colourmap it could look like this:
  369.     BMAP 0011 000F 03 00 0001 0020 0008    or
  370.     PARY 0011 000F 03 00 0001 0020 0008
  371.  
  372. When the colourmap is in the RGB32 format it would like this:
  373.     BMAP 0011 000F 03 00 0081 0020 0008    or
  374.     PARY 0011 000F 03 00 0081 0020 0008
  375.  
  376. NOTE:
  377.     The BMAP type is ever aligned to a boundary of 16:
  378.     (0x11 + 15) & -16 = 0x20
  379.     In our example (0x20 / 8 * 3) * 0xF = 180 bytes of pure datas!
  380.         [ 0x20    = aligned size of 0x11 = number of pixel in one row ]
  381.         [ 8    = 1 byte of memory can hold 8 pixel ]
  382.         [ 3    = three bitplanes ]
  383.         [ 0xF    = 15 rows ]
  384.  
  385.     The PARY type is not! aligned!!!
  386.     0x11 * 0xF = 255 bytes of pure datas!
  387.  
  388.     To make the confusion perfect: the colourmap can
  389.     lie at an odd offset; in our example at offset
  390.     (255 + 16 =) 271!!!!
  391.  
  392. A good thing is to use DOS-function Read():
  393.  
  394.     Read first 16 bytes of file!
  395.     Check type:
  396.         if BMAP compute length:
  397.             BMWidth / 8 * Depth * ImageHeight
  398.             Read the amount computed datas into data-buffer
  399.             Check Flags for colourmap
  400.             if 4-bit colourmap:
  401.                 Double Colors, since WORDs have been stored
  402.                 (Colors * 2)
  403.                 Read amount computed datas into colour-buffer
  404.             if 8-bit colourmap compute:
  405.                 Colors * 3 * 4 + 8
  406.                 (e.g.: 8 colours = 8 * 3 = 24 LONG WORDs
  407.                  24 LONG WORDs * 4 = 96 bytes
  408.                  plus 8 bytes (2 LONG WORDs)
  409.                  makes a total of 104 bytes )
  410.                 Read amount computed datas into colour-buffer
  411.         if PARY compute length:
  412.             ImageWidth * ImageHeight
  413.             Read the amount computed datas into data-buffer
  414.             Check Flags for colourmap
  415.             if 4-bit colourmap:
  416.                 Double Colors, since WORDs have been stored
  417.                 (Colors * 2)
  418.                 Read amount computed datas into colour-buffer
  419.             if 8-bit colourmap compute:
  420.                 Colors * 3 * 4 + 8
  421.                 (e.g.: 8 colours = 8 * 3 = 24 LONG WORDs
  422.                  24 LONG WORDs * 4 = 96 bytes
  423.                  plus 8 bytes (2 LONG WORDs)
  424.                  makes a total of 104 bytes )
  425.                 Read amount computed datas into colour-buffer
  426.  
  427. ---------------------------------
  428.  
  429. By the way:
  430. BitMapSaver  is  a reentrant code, you may use command resident.
  431. Up  from  Workbench  2.1  or  Kickstart 3.0 the dos-errors will appear in your
  432. native-language.
  433.  
  434.  
  435. Copyright:
  436.     BitMapSaver's  object  file and the source-code are FreeWare. Although
  437.     it's   strictly   forbidden   to   spread  the  source-code  to  other
  438.     public-domain  series  as  those created by Fred Fish. It's allowed to
  439.     upload  it  to Aminet. It's not allowed to enclose the Amiga load-file
  440.     called   BitMapSaver   to   commercial  programs  without  my  written
  441.     permission.
  442.  
  443.     Needless  to  say that I can't be held for any errors may happen using
  444.     BitMapSaver.
  445.  
  446.     (C) 1993 - 1996 J.v.d.Loo (ONIX)